package com.helin.helinhealth.service;

import com.helin.helinhealth.entity.User;

/**
 * 认证服务接口
 * 
 * <p>
 * 该接口定义了用户认证相关的业务逻辑操作，主要处理微信小程序登录认证、
 * 令牌生成与验证等功能。是整个应用安全认证的核心组件。
 * </p>
 * 
 * <p>
 * 主要功能包括：
 * - 微信小程序登录认证
 * - JWT令牌生成与解析
 * - 用户信息获取与存储
 * </p>
 */
public interface AuthService {

    /**
     * 微信小程序登录
     * 
     * <p>
     * 通过微信小程序获取的临时登录凭证（code）进行登录。
     * 该方法会调用微信服务器获取用户的openid和session_key，
     * 然后检查该用户是否已在系统中注册，如果未注册则创建新用户。
     * 最后生成JWT令牌返回给客户端用于后续接口调用身份验证。
     * </p>
     * 
     * @param code 微信小程序登录时获取的临时登录凭证
     * @return 登录结果，包含JWT令牌和用户信息
     */
    String wechatLogin(String code);
    
    /**
     * 根据openid获取用户信息
     * 
     * <p>
     * 根据微信openid获取系统中保存的用户信息。
     * 如果用户不存在，返回null。
     * </p>
     * 
     * @param openid 微信用户的唯一标识
     * @return 用户信息对象
     */
    User getUserByOpenid(String openid);
    
    /**
     * 保存或更新用户信息
     * 
     * <p>
     * 根据openid判断用户是否已存在，如果存在则更新用户信息，
     * 否则创建新用户。主要用于用户登录后更新最新的昵称、头像等信息。
     * </p>
     * 
     * @param user 用户信息对象
     * @return 是否操作成功
     */
    boolean saveOrUpdateUser(User user);
    
    /**
     * 验证JWT令牌是否有效
     * 
     * <p>
     * 检查JWT令牌的签名是否正确，是否已过期。
     * 用于API接口调用时的身份验证。
     * </p>
     * 
     * @param token JWT令牌字符串
     * @return 是否有效
     */
    boolean validateToken(String token);
    
    /**
     * 从JWT令牌中获取用户openid
     * 
     * <p>
     * 解析JWT令牌，提取其中存储的用户openid。
     * 用于在接口调用时识别当前操作的用户身份。
     * </p>
     * 
     * @param token JWT令牌字符串
     * @return 用户openid
     */
    String getOpenidFromToken(String token);
}
